<head>
<title>Compiling PyJuggler Using Visual Studio 7.1</title>
</head>

<body>

<h1>Table of Contents</h1>

<ul>
  <li><a href="#intro">Introduction</a></li>
  <li><a href="#install_pkgs">Install Required Packages</a></li>
  <li><a href="#run_buildwin32_py">Run <tt>buildwin32.py</tt></a></li>
  <li><a href="#choose_configuration">Choose a Configuration to Build</a></li>
  <li><a href="#install_vrj">Install PyJuggler</a></li>
</ul>

<a name="intro"><h1>1. Introduction to Compiling and Installing
PyJuggler</h1></a>

<p>
Building PyJuggler on Windows is straightforward.  A Visual Studio solution
has been created that collects each of the Python extension modules into
Visual C++ projects.  An overview of the steps for building and installing
PyJuggler on Windows follow:
</p>

<ol>
  <li>
    Install <a href="http://www.python.org/">Python</a> 2.2 or newer.
  </li>
  <li>
    Install <a href="http://www.vrjuggler.org/">VR Juggler</a> 2.0 Alpha 4
    or newer.
  </li>
  <li>
    Install
    <a href="http://sourceforge.net/project/showfiles.php?group_id=8041&package_id=117007">VR
    Juggler's dependencies</a>.
  </li>
  <li>
    Run <tt>buildwin32.py</tt> and fill in at least the paths to the
    required dependencies.
  </li>
  <li>
    In Visual Studio, choose the configuration(s) to build.
  </li>
  <li>
    Install the compiled libraries and example applications.
  </li>
</ol>

<p>
Each of the above steps is described in more detail below.
</p>

<a name="install_pkgs"><h1>2. Install Required Packages</h1></a>

<a name="install_python"><h2>2.1. Install Required Packages</h2></a>

<p>
In order to <a href="#run_buildwin32_py">run the helper script
<tt>buildwin32.py</tt></a>, you must have
<a href="http://www.python.org/">Python</a> 2.2 or newer installed on your
system.  Since you are interested in PyJuggler, you probably already have
Python installed.  Visit the Python website for
<a href="http://www.python.org/download/">download and install
instructions</a>.
</p>

<a name="install_vrj"><h2>2.2. Install VR Juggler</h2></a>

<p>
PyJuggler provides a Python interface to VR Juggler 2.0.  Currently,
version <a href=http://www.vrjuggler.org/vrjuggler/download-2_0.php">2.0
Alpha 4 or newer</a> is required.  Furthermore, you must get the Visual C++
7.1 build of VR Juggler 2.0.
</p>

<a name="install_vrj_deps"><h2>2.3. Install VR Juggler Dependencies</h2></a>

<p>
The easiest way to deal with VR Juggler's natively compiled dependencies
is to
<a href="http://sourceforge.net/project/showfiles.php?group_id=8041&package_id=117007">download
the pre-compiled collection of dependencies</a> that correspond to the
version of VR Juggler you have installed.
</p>

<a name="run_buildwin32_py"><h1>3. Run <tt>buildwin32.py</tt></h1></a>

<p>
Once you have Python installed, you can open the folder containing the
PyJuggler source in Windows Explorer and double-click on the icon for the
script <tt>buildwin32.py</tt>.  This script simplifies the process of building
PyJuggler on Windows by setting up paths and environment variables based on
input that you provide.  It then starts Visual Studio for you, and when the
build is complete, it will perform all the necessary installation
steps.
</p>

<p>
Regarding the environment variables, the remainder of this
section describes each of the required and optional environment variables
used by the Visual Studio build.  You can read through them to get a
better understanding of what <tt>buildwin32.py</tt> expects from your
answers to its questions, or you can
<a href="#choose_configuration">skip to the next section</a>.
</p>

<h2>3.1. Set Environment Variables</h2>

<p>
Prior to starting the Visual Studio GUI, several environment variables
must be set.  If you run the Python script <tt>buildwin32.py</tt>, all of
the necessary environment variables will be set (and cached) based on
responses you provide to several questions.

These variables provide paths to external dependencies of the Juggler
source code.  There are some environment variables that are required for
successful compilation of the Juggler source, and there are some that are
optional for getting additional code to compile.
</p>

<h3>3.1.1. Required Environment Variables</h3>

<p>
The required environment variables are as follows:
</p>

<dl>
  <dt><tt>VJ_BASE_DIR</tt></dt>
  <dd>
    The root directory of an installed copy of
    <a href="http://www.vrjuggler.org/">VR Juggler</a> 2.0 Alpha 4 or newer.
  </dd>
  <dt><tt>VJ_DEPS_DIR</tt></dt>
  <dd>
    The root directory of the collected binary dependencies of VR Juggler
    including a compiled copy of the
    <a href="http://www.boost.orb/libs/python/">Boost.Python library</a>.
    If you download the pre-packaged binary dependencies of VR Juggler,
    Boost.Python will be included.
  </dd>
  <dt><tt>BOOST_TOOL</tt></dt>
  <dd>
    The name of the Boost Jam toolset used to compile Boost.  This will
    be either <tt>vc7</tt> or <tt>vc71</tt> depending on how Boost was
    compiled.  To figure out for sure which was used, look at the names
    of the libraries in <tt>%BOOST_ROOT%\lib</tt>.  For example, the
    name of the Boost.Filesystem DLL may be
    <tt>boost_filesystem-<b>vc7</b>-mt-1_32.dll</tt> where the
    <tt>vc7</tt> part of the file name indicates that it was compiled
    using the <tt>vc7</tt> toolset.
  </dd>
  <dt><tt>BOOST_VERSION</tt></dt>
  <dd>
    The version of Boost against which the Juggler code will be compiled.
    However, this string must use underscores (<tt>_</tt>) instead of
    periods (<tt>.</tt>), and it should only reference the major and
    minor version number.  For example, if you are compiling against Boost
    1.32.2, this environment variable would be set to <tt>1_32</tt>.
  </dd>
  <dt><tt>PYTHON_ROOT</tt></dt>
  <dd>
    The root directory of an installed copy of
    <a href="http://www.python.org/">Python</a> 2.2 or newer for Windows.
  </dd>
</dl>

<a name="opt_env_vars"><h3>3.1.2. Optional Environment Variables</h3></a>

<p>
The optional environment variables are as follows:
</p>

<dl>
  <dt><tt>OSGHOME</tt></dt>
  <dd>
    The root directory of an <a href="http://www.openscenegraph.org/">Open
    Scene Graph</a> installation.  This is needed in order to build the
    <tt>vrj::OsgApp</tt> Python mapping.
  </dd>
</dl>

<a name="choose_configuration"><h1>4. Choose a Configuration to Build</h1></a>

<p>
After you answer the questions asked by <tt>buildwin32.py</tt>, the script
will start up the version of Visual Studio that you have in your path (or
that it detected on your system if your environment does not have the
<tt>devenv.exe</tt> command in your path).  Inside the Visual Studio GUI,
you must choose the configuration that you want to build.
</p>

<p>
The chosen target should be either "Debug" or "Release".  You will almost
always want to choose the "Release" configuration unless you have a Python
installation that supports loading debug extension modules.  Otherwise, select
"Batch Build" under the "Build" menu and compile everything all at once.  If
you choose to build everything but do not have all the
<a href="#opt_env_vars">optional dependencies</a>, some optional targets
such as device drivers or Java features may fail to build.  If this is not
acceptable, you must <a href="#run_buildwin32_py">go back to Step 3</a>
and run <tt>buildwin32.py</tt> again.
</p>

<a name="install_vrj"><h1>5. Install PyJuggler</h1></a>

<p>
After successfully compiling PyJuggler, <tt>buildwin32.py</tt> will ask
if you want to install PyJuggler.  On Windows, you must install PyJuggler
to be able to use it.  Working out of the development tree is not possible
the way it is on other platforms.  If you answer "yes" to the question of
installing PyJuggler, <tt>buildwin32.py</tt> will go through the full process
of installing everything that was compiled.
</p>

<p>
<font size="-1"><i>$Id$</i></font>
</p>

</body>
